Repository navigation
fix: a clonal lineage that reaches carrying capacity no longer dies for reaching it - #50
Merged
Merged
Conversation
…hing it The regulation law was the discrete logistic map, lambda*(1 - N/n_max), with a hard cap on top. Three things were wrong with it. The cap was lethal. `break 'generation` stopped at n_max exactly, so the next generation's effective rate was lambda*(1 - 1) = exactly zero and every cell drew zero offspring. Reaching capacity killed the lineage with certainty: 67 cap hits across 180 runs, 67 extinctions. Over 40 generations at lambda 4 every cap hit was fatal at every capacity tested. The engine's own carrying-capacity test ran that configuration -- lambda 4, n_max 200, seed 7 -- and asserted a bound on a population that had been extinct since generation 11. n_max was not the capacity. The logistic law settles at n_max*(1 - 1/lambda), so the parameter named a population the lineage never reached: 333 of a requested 1000 at lambda 1.5. Above lambda 3 there was no settled population at all. The map is past its period-doubling threshold there and oscillates -- 383, 827, 501, 875 at lambda 3.5; chaotically between 218 and 942 at lambda 4 -- while the comment promised a plateau. Beverton-Holt, lambda/(1 + (lambda-1)*N/n_max), fixes all three. It is monotone in N, so it cannot oscillate at any lambda, and it is exactly 1 at N = n_max, so a population at capacity replaces itself instead of dying. Its fixed point is n_max itself, which is what the parameter has always claimed to be. Sub-replacement growth is excluded rather than damped: it is already shrinking, and the denominator would turn negative. The hard cap is gone rather than repaired. A generation may now overshoot capacity and the next one is regulated back below replacement. Truncating instead has to choose which cells die, and the cheap choice -- stop at the first parent that fills the quota -- let vector position decide survival, keeping early-indexed parents' broods and dropping every later parent's brood entire. Measured overshoot is about 6%. The replayed capacity fixture was a literal control holding the old law's arithmetic, so it caught this exactly as intended. Its rates become 2.0 and 1.2, and the child the cap used to suppress is now node 8.
…s not the mean at affinity 0 The guide gave the logistic formula and said growth "plateaus instead of exploding". It plateaued at n_max*(1 - 1/lambda_base), not at n_max, and above lambda_base 3 it did not plateau at all. The parameter table said the live population "is capped at this"; nothing caps it now, and the cap was what made reaching capacity fatal. Both say what the law does, and the guide carries the version-3 note so a reader holding older data knows which law drew it. `lambda_base` was documented as the "Poisson mean for offspring count at affinity 0". A cell's actual mean is lambda_base damped by the live population and, under selection, scaled by its fitness relative to the founder -- which at affinity 0 is not generally 1. The extinction error blamed the founder for drawing zero offspring and advised raising lambda_base. Under the old law that advice made the failure more likely. It now names the two real causes, founder extinction and small-population drift, and gives the founder extinction probability so the default's 42% is not a surprise.
The lineage regulation law decides what a seed produces, so the version moves with it. The table row says which law each number means, because a dataset is only distinguishable from one drawn by the other law by this stamp. The six reproducibility goldens change by exactly one field. Compared line by line and column by column, the only value that differs across all six is `determinism_version`, 2 to 3: every sampled base, call, coordinate and counter is byte-identical. The change is confined to lineage growth, and these fixtures cover recombination, corruption and S5F -- no golden grows a lineage at all, which is why nothing here measures the new law. That gap is worth closing separately; it is also the artifact the portability question needs, since the growth path is where the engine's transcendental math lives.
The entire clonal suite passed both before and after the regulation law was replaced. 784 lineage, clonal, duplex and determinism tests, and not one of them asked how many cells were alive -- they asked what a lineage's records looked like, which the law barely touches. The only test that mentioned carrying capacity asserted a bound on the peak, and an oscillating population satisfies that, as does one that reached capacity and died twenty-nine generations before the run ended. Five of these six fail against the old law, which is how they were written: the settled population came out at n_max*(1 - 1/lambda_base) rather than n_max for all three rates, every lineage that reached capacity was extinct at the end, and the last ten generations at lambda_base 4 spanned better than 4x instead of a few percent. The premise guards are load-bearing twice over. A dead lineage settles at zero and would satisfy a one-sided bound, and a seed whose founder never establishes tests founder luck rather than regulation -- a Poisson founder dies out with probability q solving q = exp(lambda_base(q - 1)), about 0.42 at the default 1.5, so the first seed tried failed at two of the three rates for that reason alone.
The seven entries explained edits from the genotype truth sidecar branch, which is now in master. A declaration whose change is in the baseline excuses the next edit to the same name, so the gate asks for them to be deleted once they have been consumed. This branch needs none of its own: it adds a test file rather than revising one, and the Rust test renames are outside the gate's scope.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Population regulation inside
clonal_lineage()was the discrete logistic maplambda_base * max(0, 1 - P/n_max)with a hard cap on top. Three things werewrong with it, and a fourth followed.
Reaching capacity was fatal, with certainty
The cap's
break 'generationstopped atnext_live.len() == n_maxexactly,so the next generation's
1 - P/n_maxwas exactly zero, the effective rate wasexactly zero, and every cell drew zero offspring. Not a plateau — a cliff.
Measured across 180 engine runs (
n_maxin {5,20,50} xlambda_basein{1.5,2,4} x 20 seeds): 67 reached capacity, 67 went extinct in the following
generation. Over 40 generations at
lambda_base=4.0every cap hit was fatalat every capacity tested, 5 through 1000.
The engine's own
carrying_capacity_bounds_live_populationran exactly thatconfiguration —
lambda_base=4.0, n_max=200, seed=7, 40 generations— andasserted
peak_live <= n_maxandpeak_live > n_max/2on a lineage that hadbeen extinct since generation 11. It checked the peak and stopped looking.
n_maxwas never the capacity it is named forThe logistic law settles at
n_max * (1 - 1/lambda_base), so a requested 1000delivered 333 cells at the default
lambda_base=1.5, 500 at 2.0, 750 at 4.0.Above
lambda_base=3there was no settled population at allThe map is past its period-doubling threshold there. Mean-field,
n_max=1000:A silent survivorship bias, and advice that caused the failure
allow_extinction=Falseis the default. A family with no living cells yields noobserved cells, so it is counted extinct and re-grown under a fresh seed up to
50 times — meaning a family that reached capacity was discarded and resampled.
The delivered dataset quietly excluded the clones that expanded most.
When every attempt hit the cap the run raised:
Both halves wrong. The founders had grown to capacity before being killed, and
raising
lambda_basemakes a population reach the cap sooner, so following theadvice made it worse. Reproduced through the public API at
lambda_base=8.0, max_generations=40, n_max=200.The fix
Beverton-Holt:
lambda_base / (1 + (lambda_base - 1) * P / n_max).P, so it cannot oscillate at any rate.1atP = n_max: a population at capacity replaces itself.n_maxitself, which is what the parameter has always claimed.Measured final population: 1003 for
n_max=1000, 204 for 200, 48 for 50 — atevery
lambda_base. Sub-replacement growth (lambda_base <= 1) is excludedrather than damped: there is nothing to regulate, and the denominator would turn
negative past
n_max/(1-lambda_base).The hard cap is gone rather than repaired. A generation may overshoot
capacity — about 6% in practice — and the next one is regulated back below
replacement. Truncating has to choose which cells die, and the previous choice
let vector position decide: it kept the broods of early-indexed parents and
dropped every later parent's brood entire.
Compatibility
DETERMINISM_VERSION2 -> 3. Everyclonal_lineage()and duplex family runmoves; a seed does not carry across the two laws. Plain, corruption and
hypermutation runs are untouched — compared line by line and column by column,
the only field that changed in all six reproducibility goldens is
determinism_version; every sampled base, call, coordinate and counter isbyte-identical.
n_maxnow means what it says, so the samen_maxyields more cells thanbefore — about 3x at the default
lambda_base=1.5, with proportional memoryand runtime. To recover the old population, lower
n_max: the old plateau wasn_max * (1 - 1/lambda_base).Tests
The whole clonal suite passed both before and after this change. 784 lineage,
clonal, duplex and determinism tests, and not one asked how many cells were
alive.
tests/components/clonal/test_lineage_population_regulation.pyadds sixthat do; five were verified RED by rebuilding the old law, then restored
byte-identically. Their premise guards are load-bearing twice — a dead lineage
settles at zero and satisfies a one-sided bound, and a seed whose founder never
establishes tests founder luck rather than regulation (a Poisson founder dies
out with probability
q = exp(lambda_base(q-1)), about 0.42 at the default).The replayed capacity fixture was a literal control holding the old law's
arithmetic and caught this exactly as intended: rates 2.25 -> 2.0 and
0.75 -> 1.2, and the child the cap used to suppress is now node 8.
Known gap, deliberately not in this branch
No golden grows a lineage.
tests/support/golden.pycovers recombination,corruption and S5F only, which is why only the version stamp moved. A lineage
golden is worth adding, and it is also the artifact the portability question
needs, since the growth path is where
exp/ln/powflive and Rust documentstheir precision as platform-dependent. If such a golden diverges on macOS or
Windows that is a finding of its own, and it should not arrive as a red CI run
on a defect fix.
Gates
pytest 5862 passed / 17 skipped; performance 9 passed serial; cargo 1737 passed
across 6 suites; ruff clean; inventory gate clean.